// File: jmcomic-core/src/main/java/dev/jukomu/jmcomic/plugin/JmOptionPlugin.java
package dev.jukomu.jmcomic.plugin;

import dev.jukomu.jmcomic.entity.JmAlbumDetail;
import dev.jukomu.jmcomic.entity.JmPhotoDetail;

import java.util.List;
import java.util.Map;

/**
 * 对应Python的JmOptionPlugin，是所有插件的基类接口。
 */
public interface JmOptionPlugin {

    /**
     * 获取插件的唯一键名。
     *
     * @return 插件键名。
     */
    String getPluginKey();

    /**
     * 执行插件的功能。
     *
     * @param kwargs 传递给插件的参数Map。
     * @throws Exception 如果插件执行失败。
     */
    void invoke(Map<String, Object> kwargs) throws Exception;

    /**
     * 设置日志开关。
     *
     * @param logEnable 是否启用日志。
     */
    void setLogEnable(boolean logEnable);

    /**
     * 记录插件日志。
     *
     * @param msg   日志消息。
     * @param topic 日志子主题（可选）。
     */
    void log(String msg, String topic);

    /**
     * 校验参数，如果条件为假则抛出PluginValidationException。
     *
     * @param condition 条件。
     * @param message   异常消息。
     * @throws PluginValidationException 如果条件为假。
     */
    void requireParam(boolean condition, String message) throws PluginValidationException;

    /**
     * 打印库未安装的警告信息。
     *
     * @param lib     库名。
     * @param doThrow 是否抛出异常。
     * @throws PluginValidationException 如果doThrow为true。
     */
    void warningLibNotInstall(String lib, boolean doThrow) throws PluginValidationException;

    /**
     * 执行文件删除操作。
     *
     * @param paths 要删除的文件/目录路径列表。
     */
    void executeDeletion(List<String> paths);

    /**
     * 执行shell命令。
     *
     * @param cmd shell命令。
     * @return 命令执行结果。
     * @throws UnsupportedOperationException 在Java核心库中，此功能不支持。
     */
    int executeCmd(String cmd);

    /**
     * 执行多行shell命令。
     *
     * @param cmd 多行shell命令。
     * @throws UnsupportedOperationException 在Java核心库中，此功能不支持。
     */
    void executeMultiLineCmd(String cmd);

    /**
     * 将插件加入等待列表，以便主线程等待其完成。
     */
    void enterWaitList();

    /**
     * 将插件从等待列表中移除。
     */
    void leaveWaitList();

    /**
     * 等待插件完成，通常用于需要长时间运行的后台任务。
     */
    void waitUntilFinish();

    /**
     * 根据规则计算文件路径。
     *
     * @param album        本子详情（可选）。
     * @param photo        章节详情（可选）。
     * @param filenameRule 文件名规则。
     * @param suffix       文件后缀。
     * @param baseDir      基础目录。
     * @param dirRuleDict  目录规则Map（可选）。
     * @return 完整的文件路径。
     */
    String decideFilepath(JmAlbumDetail album, JmPhotoDetail photo, String filenameRule, String suffix, String baseDir, Map<String, Object> dirRuleDict);
}